## 14.4. CVS User Reference

This section provides details on connecting to a repository, the structure of sandboxes, and using the CVS commands.

### 14.4.1. Repository Locators

CVS currently supports five methods for the client to access the repository: local, external, a password server, a GSS-API (Generic Security Services API) server, and a Kerberos 4 server (most Kerberos users will want to use GSS-API). Table 14-12 describes the various repository locator types and their respective access methods.

#### Table 14-12. Repository Access Types and Methods

Method | Locator Format | Description
--- | --- | ---
Local | path | If the repository directory is local to the computer from which you will access it (or appears local, such as an NFS or Samba mounted filesystem), the repository string is just the pathname of the repository directory, such as /usr/local/cvsrep.
External | `:ext:`user`@`host`:`path | External repositories are accessed via a remote shell utility, usually rsh (the default) or ssh. The environment variable `$CVS_RSH` is used to specify the remote shell program.
Password server | `:pserver:`user`@`host`:`path | Password server repositories require authentication to a user account before allowing use of the repository. Public CVS servers are commonly configured this way so they can provide anonymous CVS access. See Section 14.3.3.11, "The passwd file", earlier in this chapter, for more information on anonymous CVS.
GSS-API server | `:gserver:` | This locator type is used for servers accessible via Kerberos 5 or other authentication mechanisms supported by GSS-API.
Kerberos server | `:kserver:` | This locator type is used for servers accessible via Kerberos 4.

### 14.4.2. Configuring CVS

CVS's behavior can be influenced by two classes of settings other than the command-line arguments: the environment variables (see Table 14-13) and special files (see Table 14-14).

#### Table 14-13. Environment Variables

Variable | Description
--- | ---
`$COMSPEC` | Command interpreter on OS/2, if not cmd.exe.
`$CVS_CLIENT_LOG` | Client-side debugging file specification for client/server connections. `$CVS_CLIENT_LOG` is the basename for the $CVS_CLIENT_LOG.in and $CVS_CLIENT_LOG.out files, which will be written in the current working directory at the time a command is executed.
`$CVS_CLIENT_PORT` `$CVS_IGNORE_REMOTE_ROOT` | The port number for :kserver: locators. `$CVS_CLIENT_PORT` doesn't need to be set if the kserver is listening on port 1999 (the default). According to the ChangeLog, this variable was removed from CVS with Version 1.10.3.
`$CVS_PASSFILE` | Password file for :PSERVER: locators. This variable must be set before issuing the cvs login to have the desired effect. Defaults to $HOME/.cvspass.
`$CVS_RCMD_PORT` | For non-Unix clients, the port for connecting to the server's rcmd daemon.
`$CVS_RSH` | Remote shell for :ext: locators, if not rsh.
`$CVS_SERVER` | Remote server program for :ext: locators, if not cvs.
`$CVS_SERVER_SLEEP` | Server-side execution delay (in seconds) to allow time to attach a debugger.
`$CVSEDITOR` | Editor used for log messages; overrides `$EDITOR`.
`$CVSIGNORE` | A list of filename patterns to ignore, separated by white space. (See also cvsignore in Table 14-4 and .cvsignore in Table 14-14.)
`$CVSREAD` | Determines read-only (if the variable is set) or read/write (if the variable is not set) for checkout and update.
`$CVSROOT` | Default repository locator.
`$CVSUMASK` | Used to determine permissions for (local) repository files.
`$CVSWRAPPERS` | A list of filename patterns for the cvswrappers function. See also Section 14.3.3, "Repository Structure".
`$EDITOR` | Specifies the editor to use for log messages; see notes for `$CVSEDITOR` earlier in this table.
`$HOME` | On Unix, used to find the .cvsrc file.
`$HOMEDRIVE` | On Windows NT, used to find the .cvsrc file.
`$HOMEPATH` | On Windows NT, used to find the .cvsrc file.
`$PATH` | Used to locate programs to run.
`$RCSBIN` | Used to locate RCS programs to run. This variable is obsolete.
`$TEMP` `$TMP` `$TMPDIR` | Location for temporary files. `$TMPDIR` is used by the server. On Unix, /tmp (and TMP on Windows NT) may not be overridden for some functions of CVS due to reliance on the system's tmpnam() function.

Despite the similarity in names, the `$CVSROOT` environment variable and the CVSROOT directory in a repository are not related to each other.

The "RSH" in the name of the `$CVS_RSH` environment variable doesn't refer to the particular program (rsh), but rather to the program CVS is supposed to use for creating remote shell connections (which could be some program other than rsh, such as ssh).

Since there is only one way to specify the remote shell program to use (`$CVS_RSH`), and since this is a global setting, users that commonly access multiple repositories may need to pay close attention to which repository they are using. If one repository requires one setting of this variable and another requires a different setting, then you will have to change this variable between accesses to repositories requiring different settings. This aspect of the repository access method is not stored in the CVS/Root file in the sandbox (see Section 14.4.4.3, "CVS directories", later in this chapter). For example, if you access some repositories via rsh and some via ssh, then you can create the following two utility aliases (bash syntax):

>     user@localhost$ alias cvs="export CVS_RSH=ssh; cvs"
>     user@localhost$ alias cvr="export CVS_RSH=rsh; cvs"

Table 14-14 shows the files used by the CVS command-line client for server connection and client configuration information. These files reside in the user's home directory.

#### Table 14-14. Client Configuration Files

Option | Description
--- | ---
~/.cvsignore | Filename patterns of files to ignore
~/.cvspass | Passwords cached by cvs login
~/.cvsrc | Default command options
~/.cvswrappers | User-specific checkout and commit filters

The ~/.cvspass file is really an operational file, not a configuration file. It is used by the cvs client program to store the repository user account password between cvs login and cvs logoff.

Some common .cvsrc settings are:

update -dP

  Brings in new directories and prunes empty directories on cvs update.

diff -c

  Give output in context diff format.

### 14.4.3. Creating a Sandbox

In order to use CVS, you must create a sandbox or have one created for you. This section describes sandbox creation, assuming there is already a module in the repository you want to work with. See Section 14.4.7.11, "import" for information on importing a new module into the repository.

1. Determine the repository locator. Talk to the repository administrator if you need help finding the repository or getting the locator syntax right.

2. If this will be the main repository you use, set `$CVSROOT`; otherwise, use the -d option when running CVS commands that don't infer the repository from the sandbox files.

3. Pick a module to check out.

4. Pick a sandbox location, and cd to the parent directory.

5. If the repository requires login, do cvs login.

6. Run cvs checkout module.

For example:

>     export CVSROOT=/usr/local/cvsroot
>     cd ~/work
>     cvs checkout hello

### 14.4.4. Sandbox Structure

This section describes the files and directories that may be encountered in sandboxes.

### 14.4.4.1. .cvsignore files

Sandboxes may contain .cvsignore files. These files specify filename patterns for files that may exist in the sandbox but which normally won't be checked into CVS. This is commonly used to cause CVS to bypass derived files.

### 14.4.4.2. .cvswrappers files

Sandboxes may contain .cvswrappers files, which provide directory-specific file handling information like that in the repository configuration file cvswrappers (see Section 14.3.3.6, "The cvswrappers file", earlier in this chapter).

### 14.4.4.3. CVS directories

Each directory in a sandbox contains a CVS directory. The files in this directory (see Table 14-15) contain metadata used by CVS to locate the repository and track which file versions have been copied into the sandbox.

#### Table 14-15. Files in the CVS Directories

File | Description
--- | ---
Base Baserev Baserev.tmp | The Base directory stores copies of files when the edit command is in use. The Baserev file contains the revision numbers of the files in Base. The Baserev.tmp file is used in updating the Baserev file.
Checkin.prog Update.prog | The programs specified in the modules file for options -i and -u, respectively (if any).
Entries | Version numbers and timestamps for the files as they were copied from the repository when checked out or updated.
Entries.Backup Entries.Log Entries.Static | These are temporary and intermediate files used by CVS.
Notify Notify.tmp | These are temporary files used by CVS for dealing with notifications for commands like edit and unedit.
Repository | The name by which the directory is known in the repository.
Root | The repository locator in effect when the sandbox was created (via cvs checkout).
Tag | Information about sticky tags and dates for files in the directory.
Template | Used to store the contents of the rcsinfo administrative file from the repository for remote repositories.

Since each sandbox directory has one CVS/Root file, a sandbox directory corresponds to exactly one repository. You cannot check out some files from one repository and some from another into a single sandbox directory.

### 14.4.5. Client Global Options

Table 14-16 lists the global options that control the operation of the CVS client program.

#### Table 14-16. Client Global Options

Option | Description
--- | ---
-a | Authenticate (gserver only).
-d root | Locate the repository. Overrides the setting of `$CVSROOT`.
-e editor | Specify message editor. Overrides the settings of `$CVSEDITOR` and `$EDITOR`.
-f | Don't read ~/.cvsrc. Useful when you have .cvsrc settings that you want to forgo for a particular command.
-H [command] --help [command] | Display help. If no command is specified, general CVS help, including a list of other help options, is displayed.
-l | Don't log command in history.
-n | Don't change any files. Useful when you want to know ahead of time which files will be affected by a particular command.
-q | Be quiet.
-Q | Be very quiet. Print messages only for serious problems.
-r | Make new working files read-only.
-s variable=value | Set the value of a user variable to a given value. User variables can be used in the contents of administrative files.
-t | Trace execution. Helpful in debugging remote repository connection problems and, in conjunction with -n, in determining the effect of an unfamiliar command.
-w | Make new working files read/write. Overrides `$CVSREAD`. Files are read/write unless `$CVSREAD` is set or -r is specified.
-x | Encrypt. (Introduced in Version 1.10.)
-z gzip_level | Set the compression level. Useful when using CVS in client/server mode across slow connections.

### 14.4.6. Common Client Options

Table 14-17 and Table 14-18 describe the options that are common to many CVS commands. Table 14-17 lists the common options with a description of their function, while Table 14-18 lists which options can be used with the user commands. In the sections that follow, details will be provided only for options that are not listed here and for those that do not function as described here.

#### Table 14-17. Common Options

Option | Description
--- | ---
-D date | Use the most recent revision no later than date.
-f | For commands that involve tags (via -r) or dates (via -D), include files not tagged with the specified tag or not present on the specified date. The most recent revision will be included.
-k kflag | Determine how keyword substitution will be performed. The space between -k and kflag is optional. See Table 14-19 for the list of keyword substitution modes.
-l | Do not recurse into subdirectories.
-n | Don't run module programs.
-R | Do recurse into subdirectories (the default).
-r rev | Use a particular revision number or symbolic tag.

Table 14-18 shows which common options are applicable to each user command.

#### Table 14-18. Client Common Option Applicability

User Command | -D | -f | -k | -l | -n | -R | -r
--- | --- | --- | --- | --- | --- | --- | ---
add |  |  |  |  |  |  |
annotate |  |  |  |  |  |  |
checkout |  |  |  |  |  |  |
commit |  |  |  |  |  |  |
diff |  |  |  |  |  |  |
edit |  |  |  |  |  |  |
editors |  |  |  |  |  |  |
export |  |  |  |  |  |  |
help |  |  |  |  |  |  |
history |  |  |  |  |  |  |
import |  |  |  |  |  |  |
log |  |  |  |  |  |  |
login |  |  |  |  |  |  |
logout |  |  |  |  |  |  |
rdiff |  |  |  |  |  |  |
release |  |  |  |  |  |  |
remove |  |  |  |  |  |  |
rtag |  |  |  |  |  |  |
status |  |  |  |  |  |  |
tag |  |  |  |  |  |  |
unedit |  |  |  |  |  |  |
update |  |  |  |  |  |  |
watch |  |  |  |  |  |  |
watchers |  |  |  |  |  |  |

### 14.4.6.1. Date formats

CVS can understand dates in a wide variety of formats, including:

ISO standard

  The preferred format is `YYYY-MM-DD HH:MM`, which would read as `2000-05-17`, or `2000-05-17 22:00`. The technical details of the format are defined in the ISO 8601 standard.

Email standard

  `17 May 2000`. The technical details of the format are defined in the RFC 822 and RFC 1123 standards.

Relative

  `10 days ago`, `4 years ago`.

Common

  month/day/year. This form can cause confusion because not all cultures use the first two fields in this order (`1/2/2000` would be ambiguous).

Other

  Other formats are accepted, including `YYYY/MM/DD` and those omitting the year (which is assumed to be the current year).

### 14.4.6.2. Keyword substitutions

Table 14-19 describes the keyword substitution modes that can be selected with the -k option. CVS uses keyword substitutions to insert revision information into files when they are checked out or updated.

#### Table 14-19. Keyword Substitution Modes

Mode | Description
--- | ---
`b` | Binary mode. Treat the file the same as with mode `o`, but also avoid newline conversion.
`k` | Keyword-only mode. Flatten all keywords to just the keyword name. Use this mode if you want to compare two revisions of a file without seeing the keyword substitution differences.
`kv` | Keyword-value mode. The keyword and the corresponding value are substituted. This is the default mode.
`kvl` | Keyword-value-locker mode. This mode is the same as `kv` mode, except it always adds the lock holder's user ID if the revision is locked. The lock is obtained via the cvs admin -l command.
`o` | Old-contents mode. Use the keyword values as they appear in the repository rather than generate new values.
`v` | Value-only mode. Substitute the value of each keyword for the entire keyword field, omitting even the `$` delimiters. This mode destroys the field in the process, so use it cautiously.

Keyword substitution fields are strings of the form `$`Keyword `...$`. The valid keywords are:

`Author`

  The user ID of the person who committed the revision.

`Date`

  The date and time (in standard UTC format) the revision was committed.

`Header`

  The full path of the repository RCS file, the revision number, the commit date, time, and user ID, the file's state, and the lock holder's user ID if the file is locked.

`Id`

  A shorter form of `Header`, omitting the leading directory name(s) from the RCS file's path, leaving only the filename.

`Name`

  The tag name used to retrieve the file, or empty if the no explicit tag was given when the file was retrieved.

`Locker`

  The user ID of the user holding a lock on the file, or empty if the file is not locked.

`Log`

  The RCS filename. In addition to keyword expansion in the keyword field, each commit adds additional lines in the file immediately following the line containing this keyword. The first such line contains the revision number, the commit date, time, and user ID. Subsequent lines are the contents of the commit log message. The result over time is a reverse-chronological list of log entries for the file. Each of the additional lines is preceded by the same characters that precede the keyword field on its line. This allows the log information to be formatted in a comment for most languages. For example:

  >     #
  >     # ch14_04.htm
  >     #
  >     # $Log: ch14_04.htm,v $
  >     # Revision 1.3  2001/06/22 16:14:09  ellie
  >     # replaced grave entity w/literal backtic
  >     #
  >     # Revision 1.2  2001/06/18 18:28:37  ellie
  >     # regenerated after xslt fixes
  >     #
  >     # Revision 1.1  2000/06/09 18:07:51  ellie
  >     # Fixed the last remaining bug in the system.
  >     #

  Be sure that you don't place any keyword fields in your log messages if you use this keyword, since they will get expanded if you do.

`RCSfile`

  The name of the RCS file (without any leading directories).

`Revision`

  The revision number of the file.

`Source`

  The full path of the RCS file.

`State`

  The file's state, as assigned by cvs admin -s (if you don't set the state explicitly, it will be `Exp` by default).

### 14.4.7. User Commands

The CVS client program provides the user commands defined in Table 14-20.

#### Table 14-20. User Commands

Command | Description
--- | ---
ad add new | Indicate that files/directories should be added to the repository.
ann annotate | Display contents of the head revision of a file, annotated with the revision number, user, and date of the last change for each line.
checkout co get | Create a sandbox for a module.
ci com commit | Commit changes from the sandbox back to the repository.
di dif diff | View differences between file versions.
edit | Prepare to edit files. This is used for enhanced developer coordination.
editors | Display a list of users working on the files. This is used for enhanced developer coordination.
ex exp export | Retrieve a module, but don't make the result a sandbox.
help | Get help.
hi his history | Display the log information for files.
im imp import | Import new modules into the repository.
lgn login logon | Log in to (cache the password for) a remote CVS server.
lo log rlog | Show the activity log for the file(s).
logout | Log off from (flush the password for) a remote CVS server.
pa patch rdiff | Release diff. The output is the format of input to Larry Wall's patch command. Does not have to be run from within a sandbox.
re rel release | p Perform a logged delete on a sandbox.
remove rm delete | Remove a file or directory from the repository.
rt rtag rfreeze | Tag a particular revision.
st stat status | Show detailed status for files.
ta tag freeze | Attach a tag to files in the repository.
unedit | Abandon file modifications and make read-only again.
up upd update | Synchronize sandbox to repository.
watch | Manage the watch settings. This is used for enhanced developer coordination.
watchers | Display the list of users watching for changes to the files. This is used for enhanced developer coordination.

### 14.4.7.1. add

>     add
>       [ -k kflag ]
>       [ -m message ]
>       file ...

Indicate that files/directories should be added to the repository. They are not actually added until they are committed via cvs commit. This command is also used to resurrect files that have been deleted with cvs remove.

The standard meaning of the common client option -k applies. There is only one additional option that can be used with the add command: -m message. This option is used to provide a description of the file (which appears in the output of the log command).

### 14.4.7.2. annotate

>     annotate
>       [ [ -D date | -r rev ] -f ]
>       [ -l | -R ]
>       file ...

CVS prints a report showing each line of the specified file. Each line is prefixed by information about the most recent change to the line, including the revision number, the user, and the date. If no revision is specified, then the head of the trunk is used.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply.

### 14.4.7.3. checkout

>     checkout
>       [ -A ]
>       [ -c | -s ]
>       [ -d dir [ -N ] ]
>       [ [ -D date | -r rev ] -f ]
>       [ -j rev1 [ -j rev2 ] ]
>       [ -k kflag ]
>       [ -l | -R ]
>       [ -n ]
>       [ -p ]
>       [ -P ]
>       module ...

Copy files from the repository to the sandbox.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are listed in Table 14-21.

#### Table 14-21. Checkout Options

Option | Description
--- | ---
-A | Reset any sticky tags or dates.
-c | Copy the module file to standard output.
-d dir | Override the default directory name.
-j rev | Join branches together.
-N | Don't shorten module paths.
-p | Pipe the files to standard output, with header lines between them showing the filename, RCS filename, and version.
-P | Prune empty directories.
-s | Show status for each module from the modules file.

### 14.4.7.4. commit

>     commit
>       [ -f | [ -l | -R ] ]
>       [ -F file | -m message ]
>       [ -n ]
>       [ -r revision ]
>       [ files ... ]

Commit the changes made to files in the sandbox to the repository.

The standard meanings of the common client options -l, -n, -r, and -R apply. Additional options are listed in Table 14-22.

#### Table 14-22. commit Options

Option | Description
--- | ---
-f | Force commit, even if no changes were made.
-F file | Use the contents of the file as the message.
-m message | Use the message specified.

Use of the -r option causes the revision to be sticky, requiring the use of admin -A to continue to use the sandbox.

### 14.4.7.5. diff

>     diff
>       [ -k kflag ]
>       [ -l | -R ]
>       [ format ]
>       [ [ -r rev1 | -D date1 ] [ -r rev2 | -D date2 ] ]
>       [ file ... ]

The diff command compares two versions of a file and displays the differences in a format determined by the options. By default, the sandbox version of the file will be compared to the repository version it was originally copied from.

The standard meanings of the common client options -D, -k, -l, -r, and -R apply. All options for the diff command in Chapter 3, "Linux Commands" can also be used.

### 14.4.7.6. edit

>     edit
>       [ -a action ]
>       [ -l | -R ]
>       [ file ... ]

The edit command is used in conjunction with watch to permit a more coordinated (serialized) development process. It makes the file writable and sends out an advisory to any users who have requested them. A temporary watch is established and will be removed automatically when either the unedit or the commit command is issued.

The standard meanings of the common client options -l and -R apply. There is only one additional option that can be used with the edit command: -a actions. This option is used to specify the actions to watch. The legal values for actions are described in the entry for the watch command.

### 14.4.7.7. editors

>     editors
>       [ -l | -R ]
>       [ file ... ]

Display a list of users working on the files specified. This is determined by checking which users have run the edit command on those files. If the edit command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also the later section on watch.

### 14.4.7.8. export

>     export
>       [ -d dir [ -N ] ]
>       [ -D date | -r rev ]
>       [ -f ]
>       [ -k kflag ]
>       [ -l | -R ]
>       [ -n ]
>       [ -P ]
>       module ...

Export files from the repository, much like the checkout command, except that the result is not a sandbox (i.e., CVS subdirectories are not created). This can be used to prepare a directory for distribution. For example:

>     user@localhost$ cvs export -r foo-1_0 -d foo-1.0 foo
>     user@localhost$ tar czf foo-1.0.tar.gz foo-1.0

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are listed in Table 14-23.

#### Table 14-23. export Options

Option | Description
--- | ---
-d dir | Use dir as the directory name instead of using the module name.
-n | Don't run any checkout programs.
-N | Don't shorten paths.

When checking out a single file located one or more directories down in a module's directory structure, the -N option can be used with -d to prevent the creation of intermediate directories.

### 14.4.7.9. help

`help`

Display helpful information about using the cvs program.

### 14.4.7.10. history

>     history
>       [ -a | -u user ]
>       [ -b string ]
>       [ -c ]
>       [ -D date ]
>       [ -e | -x type ]
>       [ -f file | -m module | -n module | -p repository ]...
>       [ -l ]
>       [ -o ]
>       [ -r rev ]
>       [ -t tag ]
>       [ -T ]
>       [ -w ]
>       [ -z zone ]
>       [ file ... ]

Display historical information. To use the history command, you must first set up the history file in the repository. See Section 14.3.3, "Repository Structure" for more information on this file.

> #### NOTE

> When used with the history command, the functions of -f, -l, -n, and -p are not the same as elsewhere in CVS.

The standard meanings of the common client options -D, and -r apply. History is reported for activity subsequent to the date or revision indicated. Additional options are listed in Table 14-24.

#### Table 14-24. history Options

Option | Description
--- | ---
-a | Show history for all users (default is current user).
-b str | Show history back to the first record containing str in the module name, filename, or repository path.
-c | Report each commit.
-e | Report everything.
-f file | Show the most recent event for file.
-l | Show last event only.
-m module | Produce a full report on module.
-n module | Report the last event for module.
-o | Report on modules that have been checked out.
-p repository | Show history for a particular repository directory.
-t tag | Show history since the tag tag was last added to the history file.
-T | Report on all tags.
-u name | Show history for a particular user.
-w | Show history only for the current working directory.
-w zone | Display times according to the time zone zone.
-x type | Report on specific types of activity. See Table 14-25.

The -p option should limit the history report to entries for the directory or directories (if multiple -p options are specified) given, but as of Version 1.10.8, it doesn't seem to affect the output. For example, to report history for the CVSROOT and hello modules, run the command:

>     cvs history -p CVSROOT -p hello

Using -t is faster than using -r because it only needs to search through the history file, not all of the RCS files.

The record types shown in Table 14-25 are generated by update commands.

#### Table 14-25. Update-Related history Record Types

Type | Description
--- | ---
`C` | Merge was necessary, but conflicts requiring manual intervention occurred.
`G` | Successful automatic merge.
`U` | Working file copied from repository.
`W` | Working copy deleted.

The record types shown in Table 14-26 are generated by commit commands:

#### Table 14-26. Commit-Related history Record Types

Type | Description
--- | ---
`A` | Added for the first time
`M` | Modified
`R` | Removed

Each of the record types shown in Table 14-27 is generated by a different command.

#### Table 14-27. Other history Record Types

Type | Command
--- | ---
`E` | export
`F` | release
`O` | checkout
`T` | rtag

### 14.4.7.11. import

>     import
>       [ -b branch ]
>       [ -d ]
>       [ -I pattern ]
>       [ -k kflag ]
>       [ -m message ]
>       [ -W spec ]
>       module
>       vendor_tag
>       release_tag ...

Import an entire directory into the repository as a new module. Used to incorporate code from outside sources or other code that was initially created outside the control of the CVS repository. More than one release_tag may be specified, in which case multiple symbolic tags will be created for the initial revision.

The standard meaning of the common client option -k applies. Additional options are listed in Table 14-28.

#### Table 14-28. import Options

Option | Description
--- | ---
-b branch | Import to a vendor branch.
-d | Use the modification date and time of the file instead of the current date and time as the import date and time. For local repository locators only.
-I pattern | Filename patterns for files to ignore.
-m message | Use message as the log message instead of invoking the editor.
-W spec | Wrapper specification.

The -k setting will apply only to those files imported during this execution of the command. The keyword substitution modes of files already in the repository are not modified.

When used with -W, the spec variable is in the same format as entries in the cvswrappers administrative file (see Section 14.3.3.6, "The cvswrappers file").

Table 14-29 describes the status codes displayed by the import command.

#### Table 14-29. import Status Codes

Status | Description
--- | ---
`C` | Changed. The file is in the repository, and the sandbox version is different; a merge is required.
`I` | Ignored. The .cvsignore file is causing CVS to ignore the file.
`L` | Link. Symbolic links are ignored by CVS.
`N` | New. The file is new. It has been added to the repository.
`U` | Update. The file is in the repository, and the sandbox version is not different.

### 14.4.7.12. log

>     log
>       [ -b ]
>       [ -d dates ]
>       [ -h ]
>       [ -N ]
>       [ -rrevisions ]
>       [ -R ]
>       [ -s state ]
>       [ -t ]
>       [ -wlogins ]
>       [ file ... ]

Print an activity log for the files.

The standard meaning of the common client option -l applies. Additional options are listed in Table 14-30.

#### Table 14-30. log Options

Option | Description
--- | ---
-b | List revisions on default branch.
-d dates | Report on these dates.
-h | Print header only.
-N | Don't print tags.
-r[revisions] | Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.
-R | Print RCS filename only. The usage of -R here is different than elsewhere in CVS (-R usually causes CVS to operate recursively).
-s state | Print only those revisions having the specified state.
-t | Print only header and descriptive text.
-w logins | Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 14-31. Multiple specifications separated by semicolons may be provided.

#### Table 14-31. log Date Range Specifications

Specification | Description
--- | ---
d1<d2, or d2>d1 | The revisions dated between d1 and d2, exclusive
d1<=d2, or d2>=d1 | The revisions dated between d1 and d2, inclusive
<d, or d> | The revisions dated before d
<=d, or d>= | The revisions dated on or before d
d<, or >d | The revisions dated after d
d<=, or >=d | The revisions dated on or after d
d | The most recent revision dated d or earlier

For -r, use the revision specifications in Table 14-32.

#### Table 14-32. log Revision Specifications

Specification | Description
--- | ---
rev1: rev2 | The revisions between rev1 and rev2, inclusive.
:rev | The revisions from the beginning of the branch to rev, inclusive.
rev: | The revisions from rev to the end of the branch, inclusive.
branch | All revisions on the branch.
branch1: branch2 | All revisions on all branches between branch1 and branch2 inclusive.
branch`.` | The latest revision on the branch.

For rev1:rev2, it is an error if the revisions are not on the same branch.

### 14.4.7.13. login

>     login

This command is used to log in to remote repositories. The password entered will be cached in the ~/.cvspass file, since a connection to the server is not maintained across invocations.

### 14.4.7.14. logout

>     logout

This command logs out of a remote repository. The password cached in the ~/.cvspass file will be deleted.

### 14.4.7.15. rdiff

>     rdiff
>       [ -c | -s | -u ]
>       [ { { -D date1 | -r rev1 } [ -D date2 | -r rev2 ] } | -t ]
>       [ -f ]
>       [ -l | -R ]
>       [-V vn]
>       file ...

The rdiff command creates a patch file that can be used to convert a directory containing one release into a different release.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-33.

#### Table 14-33. rdiff Options

Option | Description
--- | ---
-c | Use context diff format (the default).
-s | Output a summary of changed files instead of a patch file.
-t | Show the differences between the two most recent revisions.
-u | Use unidiff format.
-V rcsver | Obsolete. Used to specify version of RCS to emulate for keyword expansion. (Keyword expansion emulates RCS Version 5.)

### 14.4.7.16. release

>     release
>       [ -d ]
>       directory ...

Sandboxes can be abandoned or deleted without using cvs release if desired; using the release command will log an entry to the history file (if this mechanism is configured) about the sandbox being destroyed. In addition, it will check the disposition (recursively) of each of the sandbox files before deleting anything. This can help prevent destroying work that has not yet been committed.

There is only one option that can be used with the release command, -d. The -d option will delete the sandbox copy if no uncommitted changes are present.

> #### NOTE

> New directories (including any files in them) in the sandbox will be deleted if the -d option is used with release.

The status codes listed in Table 14-34 are used to describe the disposition of each file encountered in the repository and the sandbox.

#### Table 14-34. release Status Codes.

Status | Description
--- | ---
`A` | The sandbox file has been added (the file was created and cvs add was run), but the addition has not been committed.
`M` | The sandbox copy of the file has been modified.
`P` `U` | Update available. There is a newer version of the file in the repository, and the copy in the sandbox has not been modified.
`R` | The sandbox copy was removed (the file was deleted and cvs remove was run), but the removal was not committed.
`?` | The file is present in the sandbox but not in the repository.

### 14.4.7.17. remove

>     remove
>       [ -f ]
>       [ -l | -R ]
>       [ file ... ]

Indicate that files should be removed from the repository. The files will not actually be removed until they are committed. Use cvs add to resurrect files that have been removed if you change your mind later.

The standard meanings of the common client options -l and -R apply. Only one other option may be used with the remove command, -f. When used, -f will delete the file from the sandbox first.

### 14.4.7.18. rtag

>     rtag
>       [ -a ]
>       [ -b ]
>       [ -d ]
>       [ -D date | -r rev ]
>       [ -f ]
>       [ -F ]
>       [ -l | - R ]
>       [ -n ]
>       tag
>       file ...

Assign a tag to a particular revision of a set of files. If the file already uses the tag for a different revision, cvs rtag will complain unless the -F option is used. This command does not refer to the sandbox file revisions (use cvs tag for that), so it can be run outside of a sandbox, if desired.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-35.

#### Table 14-35. rtag Options

Option | Description
--- | ---
-a | Search the Attic for removed files containing the tag.
-b | Make it a branch tag.
-d | Delete the tag.
-F | Force. Move the tag from its current revision to the one specified.
-n | Don't run any tag program from the modules file.

### 14.4.7.19. status

>     status
>       [ -l | -R ]
>       [ -v ]
>       [ file ... ]

Display the status of the files.

The standard meanings of the common client options -l and -R apply. The other option that can be used with the status command, -v, may be used to include tag information.

### 14.4.7.20. tag

>     tag
>       [ -b ]
>       [ -c ]
>       [ -d ]
>       [ -D date | -r rev ]
>       [ -f ]
>       [ -F ]
>       [ -l | R ]
>       tag
>       [ file ... ]

Assign a tag to the sandbox revisions of a set of files. You can use the status -v command to list the existing tags for a file.

The tag must start with a letter and must consist entirely of letters, numbers, dashes (`-`) and underscores (`_`). Therefore, while you might want to tag your hello project with `1.0` when you release Version 1.0, you'll need to tag it with something like `hello-1_0` instead.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are listed in Table 14-36.

#### Table 14-36. tag Options

Option | Description
--- | ---
-b | Make a branch.
-c | Check for changes. Make sure the files are not locally modified before tagging.
-d | Delete the tag.
-F | Force. Move the tag from its current revision to the one specified.

Since the -d option throws away information that might be important, it is recommended that you use it only when absolutely necessary. It is usually better to create a different tag with a similar name.

### 14.4.7.21. unedit

>     unedit
>       [ -l | -R ]
>       [ file ... ]

Abandon file modifications and make the file read-only again. Watchers will be notified.

The standard meanings of the common client options -l and -R apply.

### 14.4.7.22. update

>     update
>       [ -A ]
>       [ -d ]
>       [ -D date | -r rev ]
>       [ -f ]
>       [ -I pattern ]
>       [ -j rev1 [ -j rev2 ] ]
>       [ -k kflag ]
>       [ -l | -R ]
>       [ -p ]
>       [ -P ]
>       [ -W spec ]
>       [ file ... ]

Update the sandbox, merging in any changes from the repository. For example:

>     cvs -n -q update -AdP

can be used to do a quick status check of the current sandbox versus the head of the trunk of development.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are listed in Table 14-37.

#### Table 14-37. update Options

Option | Description
--- | ---
-A | Reset sticky tags.
-d | Create and update new directories.
-I pattern | Provide filename patterns for files to ignore.
-j revision | Merge in changes between two revisions. Mnemonic: join.
-p | Check out files to standard output.
-P | Prune empty directories.
-W spec | Provide wrapper specification.

Using -D or -r results in sticky dates or tags, respectively, on the affected files (using -p along with these prevents stickiness). Use -A to reset any sticky tags or dates.

If two -j specifications are made, the differences between them are computed and applied to the current file. If only one is given, then the common ancestor of the sandbox revision and the specified revision is used as a basis for computing differences to be merged.

For example, suppose a project has an experimental branch, and important changes to the file foo.c were introduced between revisions 1.2.2.1 and 1.2.2.2. Once those changes have proven stable, you want them reflected in the main line of development. From a sandbox with the head revisions checked out, we run:

>     user@localhost$ cvs update -j 1.2.2.1 -j 1.2.2.2 foo.c

CVS finds the differences between the two revisions and applies those differences to the file in our sandbox.

The spec used with -W is in the same format as entries in the cvswrappers administrative file (see Section 14.3.3.6, "The cvswrappers file").

The status codes listed in Table 14-38 are used to describe the action taken on each file encountered in the repository and the sandbox.

#### Table 14-38. update Status Codes

Status Code | Description
--- | ---
`A` | Added. Server took no action because there was no repository file. Indicates that cvs add, but not cvs commit, has been run.
`C` | Conflict. Sandbox copy is modified (it has been edited since it was checked out or last committed). There was a new revision in the repository, and there were conflicts when CVS merged its changes into the sandbox version.
`M` | Modified. Sandbox copy is modified (it has been edited since it was checked out or last committed). If there was a new revision in the repository, its changes were successfully merged into the file (no conflicts).
`P` | Patched. Same as `U` but indicates the server used a patch.
`R` | Removed. Server took no action. Indicates that cvs remove, but not cvs commit, has been run.
`U` | Updated. The file was brought up-to-date.
`?` | File is present in sandbox but not in repository.

### 14.4.7.23. watch

>     watch
>       { { on | off } | { add | remove } [ -a action ] }
>       [ -l | -R ]
>       file ...

The watch command controls CVS's edit-tracking mechanism. By default, CVS operates in its concurrent development mode, allowing any user to edit any file at any time. CVS includes this watch mechanism to support developers who would rather be notified of edits made by others proactively than discover them when doing an update.

The CVSROOT/notify file determines how notifications are performed.

Table 14-39 shows the watch sub-commands and their uses.

#### Table 14-39. watch Sub-commands

Sub-command | Description
--- | ---
add | Start watching files.
off | Turn off watching.
on | Turn on watching.
remove | Stop watching files.

The standard meanings of the common client options -l and -R apply. The only other option that can be used with the watch command is -a action. The -a option is used in conjunction with one of the actions listed in Table 14-40.

#### Table 14-40. watch Actions

Action | Description
--- | ---
`all` | All of the following.
`commit` | A user has committed changes.
`edit` | A user ran cvs edit.
`none` | Don't watch. Used by the edit command.
`unedit` | A user ran cvs unedit, cvs release, or deleted the file and ran cvs update, re-creating it.

See also the descriptions of the edit, editors, unedit, and watchers commands.

### 14.4.7.24. watchers

>     watchers
>       [ -l | -R ]
>       [ file ... ]

Display a list of users watching the specified files. This is determined by checking which users have run the watch command on a particular file (or set of files). If the watch command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.

Copyright © 2001 O'Reilly & Associates. All rights reserved.